Forge Your Defense • Stay Vigilant

---

A modern, high-performance Threat Intelligence Platform built with Rust and React. Collect, enrich, and analyze Indicators of Compromise (IOCs) with automatic type detection and real-time enrichment.

✨ Features

Feature	Description
🎯 Multi-type IOC Support	IPs, domains, URLs, hashes, emails, and CVEs
🔍 Auto-detection	Automatically identifies IOC type from input
🌍 Real-time Enrichment	GeoIP, DNS, VirusTotal, AbuseIPDB integration
🖥️ Cyberpunk Dashboard	Beautiful React UI with terminal aesthetics
🔌 RESTful API	Full-featured API for automation and integration
🗄️ PostgreSQL Backend	Reliable storage with full-text search
🏷️ Tagging & Severity	Organize and prioritize threats
🚦 TLP Support	Traffic Light Protocol for sharing classification

🏗️ Architecture

flowchart TB
    subgraph Clients
        UI[React Dashboard<br/>:3000]
        API_CLIENT[API Clients<br/>curl/scripts]
        HONEYPOT[HoneyTrap<br/>Honeypot]
    end

    subgraph SentinelForge Backend
        API[Axum REST API<br/>:8080]
        
        subgraph Enrichment Engine
            GEOIP[GeoIP<br/>MaxMind]
            DNS[DNS<br/>Resolver]
            VT[VirusTotal<br/>API]
            ABUSE[AbuseIPDB<br/>API]
        end
        
        subgraph Storage Layer
            REPO[ThreatIntel<br/>Repository]
            PG[(PostgreSQL<br/>Database)]
        end
    end

    subgraph External Services
        MAXMIND[MaxMind<br/>GeoLite2]
        VT_API[VirusTotal<br/>API]
        ABUSE_API[AbuseIPDB<br/>API]
    end

    UI -->|HTTP| API
    API_CLIENT -->|HTTP| API
    HONEYPOT -->|HTTP| API
    
    API --> REPO
    REPO --> PG
    
    API --> GEOIP
    API --> DNS
    API --> VT
    API --> ABUSE
    
    GEOIP -.->|mmdb| MAXMIND
    VT -.->|REST| VT_API
    ABUSE -.->|REST| ABUSE_API

    style UI fill:#00ffaa,stroke:#000,color:#000
    style API fill:#ff6b00,stroke:#000,color:#fff
    style PG fill:#316192,stroke:#000,color:#fff
    style GEOIP fill:#ffd000,stroke:#000,color:#000
    style DNS fill:#ffd000,stroke:#000,color:#000
    style VT fill:#ffd000,stroke:#000,color:#000
    style ABUSE fill:#ffd000,stroke:#000,color:#000

Loading

🔄 Data Flow

sequenceDiagram
    participant C as Client
    participant A as API
    participant D as Detector
    participant E as Enrichment
    participant DB as PostgreSQL

    C->>A: POST /api/v1/indicators<br/>{"value": "8.8.8.8"}
    A->>D: Detect IOC Type
    D-->>A: Type: IP
    A->>DB: Upsert Indicator
    DB-->>A: Indicator Created
    
    par Async Enrichment
        A->>E: Enrich (GeoIP)
        E-->>DB: Save: Country, ASN
        A->>E: Enrich (DNS)
        E-->>DB: Save: PTR Record
        A->>E: Enrich (VirusTotal)
        E-->>DB: Save: Reputation
    end
    
    A-->>C: 201 Created<br/>{indicator + id}

Loading

🚀 Quick Start

Prerequisites

• Rust 1.70+
• PostgreSQL 14+
• Node.js 18+ (for frontend)

Backend Setup

# Clone the repository
git clone https://github.com/lloredia/SentinelForge.git
cd SentinelForge

# Set up database
export DATABASE_URL="postgresql://postgres:postgres@localhost:5432/sentinelforge"
createdb sentinelforge

# Run migrations
cargo install sqlx-cli --no-default-features --features postgres
sqlx migrate run

# Build and run
cargo build --release
./target/release/sentinelforge

Frontend Setup

cd sentinelforge-ui
npm install
npm start

The dashboard will be available at http://localhost:3000

GeoIP Setup (Optional)

1. Sign up for a free MaxMind account: https://www.maxmind.com/en/geolite2/signup
2. Download GeoLite2-City and GeoLite2-ASN databases
3. Place .mmdb files in the data/ directory

📡 API Reference

Health Check

curl http://localhost:8080/health

Create Indicator

curl -X POST http://localhost:8080/api/v1/indicators \
  -H "Content-Type: application/json" \
  -d '{"value": "8.8.8.8", "severity": "low", "tags": ["dns", "google"]}'

List Indicators

curl http://localhost:8080/api/v1/indicators

Lookup by Value

curl "http://localhost:8080/api/v1/lookup?value=8.8.8.8"

Get Statistics

curl http://localhost:8080/api/v1/stats

Bulk Import

curl -X POST http://localhost:8080/api/v1/indicators/bulk \
  -H "Content-Type: application/json" \
  -d '{
    "source": "threat-feed",
    "indicators": [
      {"value": "1.2.3.4", "severity": "high"},
      {"value": "evil.com", "severity": "critical"}
    ]
  }'

📋 API Endpoints

Method	Endpoint	Description
GET	/health	Health check
GET	/api/v1/indicators	List indicators (paginated)
POST	/api/v1/indicators	Create indicator
GET	/api/v1/indicators/:id	Get indicator by ID
DELETE	/api/v1/indicators/:id	Delete indicator
POST	/api/v1/indicators/:id/enrich	Trigger enrichment
POST	/api/v1/indicators/:id/sightings	Add sighting
GET	/api/v1/lookup	Lookup by value
GET	/api/v1/stats	Dashboard statistics
POST	/api/v1/indicators/bulk	Bulk import
GET	/api/v1/sources	List feed sources

🎯 IOC Types

Type	Example	Auto-detected
IP	8.8.8.8, 2001:4860:4860::8888	✅
Domain	malicious-domain.com	✅
URL	https://evil.com/malware.exe	✅
Hash	MD5, SHA1, SHA256	✅
Email	attacker@evil.com	✅
CVE	CVE-2024-1234	✅

🔌 Enrichment Providers

Provider	Data	API Key Required
MaxMind GeoIP	Country, City, ASN, Org	Free account
DNS	PTR, A, MX records	❌
VirusTotal	Reputation, detections	✅
AbuseIPDB	Abuse reports, confidence	✅

Configure API Keys

export VIRUSTOTAL_API_KEY="your-api-key"
export ABUSEIPDB_API_KEY="your-api-key"

📁 Project Structure

sentinelforge/
├── src/
│   ├── main.rs              # Application entry point
│   ├── api/                  # REST API handlers
│   ├── models/               # Data models & IOC utils
│   ├── storage/              # Database operations
│   ├── enrichment/           # Enrichment providers
│   │   ├── geoip.rs          # MaxMind GeoIP
│   │   ├── dns.rs            # DNS lookups
│   │   ├── virustotal.rs     # VirusTotal API
│   │   ├── abuseipdb.rs      # AbuseIPDB API
│   │   └── whois.rs          # WHOIS lookups
│   └── collectors/           # Threat feed collectors
├── migrations/               # Database migrations
├── data/                     # GeoIP databases
├── sentinelforge-ui/         # React dashboard
└── Cargo.toml

🐳 Docker Deployment

# Build
docker build -t sentinelforge .

# Run with PostgreSQL
docker-compose up -d

🗺️ Roadmap

• STIX/TAXII integration
• Automated threat feed ingestion
• Alert notifications (email, Slack, webhooks)
• MITRE ATT&CK mapping
• API rate limiting
• User authentication
• HoneyTrap honeypot integration

🤝 Contributing

Contributions are welcome! Please open an issue or submit a pull request.

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

• MaxMind for GeoIP databases
• Axum for the web framework
• SQLx for async database operations

---

SentinelForge - Forge Your Defense